/*
 * Flashlib - QB9 common Flash library
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package com.qb9.flashlib.audio
{
	/**
	 * Common interface for AudioManager and AudioMixer.
	 */
	public interface IAudioManager
	{
		/**
		 * Start/resume playback of one or more registered assets.
		 * 
		 * @param id Optional string with one or more comma/space separated ids. If left null, then the action is taken on all the registered assets.
		 * 
		 * @see IPlayable#stop()
		 * @see IPlayable#play()
		 */
		function play(id:String = null) : IAudioManager;
		
		/**
		 * Start playing one or more registered assets from the beginning as many times as specified.
		 * If the id is null, then the action is taken on all the registered assets.
		 * 
		 * @param id Optional string with one or more comma/space separated ids. If left null, then the action is taken on all the registered assets.
		 * @param times The amount of times the playback should be repeated, endless by default.
		 * 
		 * @see IPlayable#stop()
		 * @see IPlayable#loop()
		 */
		function loop(id:String = null, times:int = int.MAX_VALUE) : IAudioManager;
		
		/**
		 * Resume the playback of one or more registered assets (only if previously paused).
		 *
		 * @param id Optional string with one or more comma/space separated ids. If left null, then the action is taken on all the registered assets.
		 * 
		 * @see #pause()
		 * @see IPlayable#play()
		 * @see IPlayable#pause()
		 */
		function resume(id:String = null) : IAudioManager;
		
		/**
		 * Stop the playback of one or more registered assets.
		 * 
		 * @param id Optional string with one or more comma/space separated ids. If left null, then the action is taken on all the registered assets.
		 *
		 * @see IPlayable#stop()
		 */
		function stop(id:String = null) : IAudioManager;

		/**
		 * Pause the playback of one or more registered assets.
		 * 
		 * @param id Optional string with one or more comma/space separated ids. If left null, then the action is taken on all the registered assets.
		 *
		 * @see #resume()
		 * @see IPlayable#pause()
		 */
		function pause(id:String = null) : IAudioManager;
		
		/**
		 * Mute one or more registered assets.
		 * 
		 * @param id Optional string with one or more comma/space separated ids. If left null, then the action is taken on all the registered assets.
		 *
		 * @see #unmute
		 * @see IPlayable#mute()
		 */
 		function mute(id:String = null) : IAudioManager;
		
		/**
		 * Unmute one or more registered assets. The previous volume level is preserved.
		 * 
		 * @param id Optional string with one or more comma/space separated ids. If left null, then the action is taken on all the registered assets.
		 *
		 * @see #mute
		 * @see IPlayable#unmute()
		 */
		function unmute(id:String = null) : IAudioManager;
		
		/**
		 * Set the internal stored gain for one or more registered assets.
		 *
		 * <p>The gain is the asset's volume, in relation to the masterVolume.</p>
		 * 
		 * @param id Optional string with one or more comma/space separated ids. If left null, then the action is taken on all the registered assets.
		 * @param gain A number between 0-1 to be multiplied with the master volume.
		 */
		function gain(id:String, gain:Number) : IAudioManager;
		
		/**
		 * Remove one or more registered assets.
		 * 
		 * @param id Optional string with one or more comma/space separated ids. If left null, then the action is taken on all the registered assets.
		 */
		function remove(id:String = null) : IAudioManager;
		
		/**
		 * Returns wether or not the asset with the given id is registered.
		 */
		function has(id:String) : Boolean;
		
		/** Returns a reference to the registered asset. */
		function retrieve(id:String) : IPlayable;
		
		/**
		 * Global volume multiplied by each IPlayable's gain.
		 * @see #gain()
		 */
		function get masterVolume() : Number;
		
		/** @private */
		function set masterVolume(num:Number) : void;
	}
}
